Split `commons()` into two by simonpcouch · Pull Request #414 · posit-dev/commons

simonpcouch · 2026-10-09T20:17:31Z

...with interoperability in mind. Closes #410. The recommended way to write:

agent <- commons(client, data_sources, semantic_layer, context_layer)

becomes:

commons <- commons(data_sources, semantic_layer, context_layer)
agent <- agent(client, commons)

Implemented backward-compatibly.

commons()'s output is "just" the data structure that holds the trusted code and output, and not the stuff that hooks into an agent harness so external agents can invoke search and call trusted code and context via methods on the output.

For external coding agents, the flow is that they'd register mcp-console with commons <- commons() in the startup script and a sentence added to the tool descriptuon. For Posit Assistant, this would be an entry in .Rprofile and a sentence in AGENTS.md.

simonpcouch · 2026-10-09T21:18:10Z

Will need to think through DuckDB and context search:

DuckDB extensions don't reach other packages' connections. mcp-console installs extensions into its own cache, but only its own SQL connection reads that cache. ragnar's connection (commons' context search) looks in ~/.duckdb instead. Setting DUCKDB_R_HOME for the R worker would likely fix it, though I haven't checked the folder layout lines up. The demo works today only because fts for DuckDB 1.5.6 got cached in ~/.duckdb during my earlier testing; on a fresh machine, context search would fail.

simonpcouch · 2026-10-22T16:27:00Z

MCP-CONSOLE ALLOWS US TO EDIT THE TOOL DESCRIPTION NOW YIPPEE

simonpcouch · 2026-10-22T18:51:18Z

https://t-kalinowski.github.io/mcp-console/build_on_console/

# Conflicts: # pkg-r/R/commons.R

github-actions · 2026-10-23T13:57:30Z

Preview deployed to Connect (dogfood.team.pct.posit.it): https://dogfood.team.pct.posit.it/connect/#/apps/d7a36cae-8f27-448b-a478-61b81fbe3942/draft/384054

Deployed from commit 15aa5d0.

github-actions · 2026-10-23T13:58:46Z

Preview deployed to Connect (connect.staging.pct.posit.it): https://connect.staging.pct.posit.it/connect/#/apps/ad662e1b-5048-4acc-9ad7-f9478c92274e/draft/3930

Deployed from commit 15aa5d0.

simonpcouch · 2026-10-23T16:01:59Z

In devrel-agent with Posit Assistant:

commons-in-posit-assistant.mov

simonpcouch · 2026-10-23T16:37:17Z

We should talk about how to make multiple commons agents available in one R session in the docs.

hadley · 2026-10-23T16:57:01Z

Regardless of anything else you should recommend a fully named call for trusted(data_sources, semantic_layer, context_layer), so it's easier to change in the future.

simonpcouch · 2026-10-23T18:15:36Z

[EDIT: this is now done]

Should rename commons() to agent() and then trusted() to commons(). The output of commons() is "the commons", and the output of agent() is what (former) commons() used to return. We can make this backward-compatible by dispatching based on the classes and adding ellipses.

commons <- commons(data_sources = data_sources, semantic_layer = semantic_layer, context_layer = context_layer)
agent <- agent(client, commons = commons)

client = supplied to commons() could go to ..., triggering a deprecation warning. Mayyybe just put the new commons() arguments after ... to force them to be named? Unless that would cause breakages.

For now, this should be backward-compatible, raising a deprecate_warn().

`commons()` now returns the commons: data sources, semantic layer, and context layer, callable without a model. Its arguments must be named. `agent(client, commons = )` builds the agent. Calls that pass a client to `commons()` still return an agent, with a deprecation warning.

simonpcouch · 2026-10-26T14:22:40Z

See here for the write-up of the changes.

simonpcouch · 2026-10-26T14:23:40Z

+#' If the commons has a context layer, `$context()` needs one more step for
+#' now. It relies on DuckDB's `fts` extension, which MCP Console's sandbox
+#' can't download. MCP Console can install the extension itself, but only
+#' into its own cache, which R's duckdb doesn't read by default. Point R at
+#' that cache with an absolute path (`~` and environment variables aren't
+#' expanded):
+#'
+#' ```yaml
+#' environment:
+#'   # macOS; on Linux, /home/you/.cache/mcp-console/dependencies/duckdb
+#'   DUCKDB_R_HOME: /Users/you/Library/Caches/mcp-console/dependencies/duckdb
+#' ```
+#'
+#' Then add one more sentence to both `tool.description` and
+#' `tool.instructions`, so the agent asks MCP Console to install the
+#' extension:
+#'
+#' ```markdown
+#' The first time you run `commons$context()`, include
+#' `"requirements": {"duckdb": ["fts"]}` in the same call.
+#' ```


There's a comment above about an issue with the needed extensions for DuckDB and context search. I decided to just temporarily document the workaround for users in favor of #455, removing the needed for ragnar/duckdb in context search altogether.

Another approach could be to have Tomasz add a configuration option in mcp-console that would allow us to pre-install extensions on install.

simonpcouch · 2026-10-26T14:36:04Z

Agent-written code review from GPT 6.1 Sol — two findings

Reviewed ee1da47.

[P2] Preserve quoted literals in where strings (pkg-r/R/commons.R:455–458). Parsing removes quotes, and compile_where_triple() subsequently emits numeric-looking strings as numbers. With character regions c("001", "1"), $metrics("n_orders", where = "region = '001'") returns 2, while the same SQL predicate returns 1. Preserve the literal's string type through compilation so filtering does not silently change the result.

[P2] Load pending pins before returning their connection (pkg-r/R/commons.R:285–287). A fresh pins-backed commons returns an empty DuckDB connection, so the documented direct-query fallback fails with “Table with name orders does not exist.” The same query works after $describe("orders") loads the pin. Call source_ensure_all(src) before exposing the connection.

Both reproduced locally. Focused commons and agent tests pass; the full suite was not run.

Edit: addressed both.

skaltman · 2026-10-26T21:01:21Z

I will take a closer look at this in a bit, but what do you think about also having a way to resolve custom SQL that uses dictionary definitions? Ordinary SQL can already be run with $connection.

I have not thought about this much from an interoperability angle, but it would be helpful (but not critical) for the reproducibility work in #428. It would be useful from an interoperability stance if you want to write custom SQL that uses a dictionary definition without copying and pasting from the dictionary.

simonpcouch · 2026-10-27T13:14:27Z

I will take a closer look at this in a bit, but what do you think about also having a way to resolve custom SQL that uses dictionary definitions? Ordinary SQL can already be run with $connection.

Thanks, this was an oversight on my part. $connection() is now $run_sql() and resolves dictionary definitions in the way that the commons agents' tool does :)

$run_sql() expands governed definitions as {{name}} tokens and refuses writes, as the agent's run_sql tool does. MCP Console now builds commons from .Rprofile, since its startup block must select a SQL connection.

jat255

Generally, I like this direction. Some small comments and a few little R things identified by Opus (I verified, but definitely wouldn't have found them without it :D).

I'll open an issue to bring Python in sync with this architecture.

…learer empty-list errors

github-actions · 2026-10-28T13:47:55Z

Cleaned up 15 preview bundle(s) on https://dogfood.team.pct.posit.it: 382623, 382626, 382629, 382630, 382631, 382634, 382639, 382642, 383283, 383284, 383291, 383294, 383664, 383666, 384054

github-actions · 2026-10-28T13:48:07Z

Cleaned up 15 preview bundle(s) on https://connect.staging.pct.posit.it: 3737, 3738, 3739, 3740, 3741, 3742, 3744, 3746, 3782, 3785, 3786, 3788, 3849, 3851, 3930

Prototype trusted() in R, with commons() accepting one

385de4a

simonpcouch commented Oct 9, 2026

View reviewed changes

Return plain values from trusted methods, without handles

c1d97d6

This comment was marked as outdated.

Sign in to view

simonpcouch commented Oct 9, 2026

View reviewed changes

Comment thread pkg-r/R/trusted.R Resolved

Merge remote-tracking branch 'origin/main' into interop

88f6b99

# Conflicts: # pkg-r/R/commons.R

simonpcouch added 7 commits October 23, 2026 09:03

Document using trusted() with coding agents through MCP Console

f96fafe

Point trusted's printout at $search() and a $context() query

c7e0475

Phrase trusted's search results as its own methods, not agent tools

192166b

Accept SQL-like strings and unnamed triples for trusted's where

fc23bec

List trusted's method signatures and document setup per coding agent

b2ebb79

rewrite docs

1c6328c

Only list trusted's calculation methods that have something to run

ef7e7c7

simonpcouch added 2 commits October 26, 2026 08:12

rewrite NEWS.md

5edc0bf

simonpcouch mentioned this pull request Oct 26, 2026

Consider transitioning from RAG to grep in context search #455

Open

Document the MCP Console workaround for context search's fts extension

ee1da47

simonpcouch commented Oct 26, 2026

View reviewed changes

Fix quoted predicates and lazy pins in commons methods

dec36ca

simonpcouch marked this pull request as ready for review October 26, 2026 14:44

simonpcouch requested review from jat255 and skaltman October 26, 2026 14:44

simonpcouch mentioned this pull request Oct 26, 2026

Make calculations transparent and reproducible #428

Closed

skaltman mentioned this pull request Oct 26, 2026

Add vignette and skill ref to reproduce analyses; add user to logged trajectories #457

Merged

simonpcouch added 2 commits October 27, 2026 08:15

Replace commons' $connection() with $run_sql()

befbef0

$run_sql() expands governed definitions as {{name}} tokens and refuses writes, as the agent's run_sql tool does. MCP Console now builds commons from .Rprofile, since its startup block must select a SQL connection.

document languages: [r]

0a7131f

jat255 approved these changes Oct 27, 2026

View reviewed changes

jat255 mentioned this pull request Oct 27, 2026

Split the Python Commons agent into a commons object and an agent #459

Open

simonpcouch added 2 commits October 28, 2026 08:39

Address review: stricter where parsing, hide $context() when empty, c…

6df2acf

…learer empty-list errors

Test $calculation(), $context(), and $describe() on commons objects

15aa5d0

simonpcouch merged commit 75c815a into main Oct 28, 2026
10 checks passed

simonpcouch deleted the interop branch October 28, 2026 13:47

simonpcouch mentioned this pull request Oct 30, 2026

Add artifacts #404

Open

Conversation

simonpcouch commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

simonpcouch commented Oct 9, 2026

Uh oh!

This comment was marked as outdated.

Uh oh!

simonpcouch commented Oct 22, 2026

Uh oh!

simonpcouch commented Oct 22, 2026

Uh oh!

github-actions Bot commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

simonpcouch commented Oct 23, 2026

Uh oh!

simonpcouch commented Oct 23, 2026

Uh oh!

hadley commented Oct 23, 2026

Uh oh!

simonpcouch commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

simonpcouch Oct 26, 2026

Choose a reason for hiding this comment

Uh oh!

simonpcouch Oct 26, 2026

Choose a reason for hiding this comment

Uh oh!

simonpcouch commented Oct 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

skaltman commented Oct 26, 2026

Uh oh!

simonpcouch commented Oct 27, 2026

Uh oh!

jat255 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Oct 28, 2026

Uh oh!

github-actions Bot commented Oct 28, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

simonpcouch commented Oct 9, 2026 •

edited

Loading

github-actions Bot commented Oct 23, 2026 •

edited

Loading

github-actions Bot commented Oct 23, 2026 •

edited

Loading

simonpcouch commented Oct 23, 2026 •

edited

Loading

simonpcouch commented Oct 26, 2026 •

edited

Loading